Refresh docs site theme toward neutral GitHub-style surfaces by Copilot · Pull Request #40422 · github/gh-aw

Copilot · 2026-06-20T03:30:36Z

The docs site had drifted into a heavily purple treatment across all pages. This change pulls the shared light and dark themes back toward neutral GitHub-like surfaces while preserving a more distinctly purple visual identity on the landing page.

Theme tokens and shared surfaces
- Introduce shared --aw-* tokens for neutral page backgrounds, elevated surfaces, borders, muted text, shadows, and accent tinting.
- Rebalance the default dark theme and light theme to use quieter neutrals with purple reserved for emphasis rather than full-page treatment.
Non-homepage docs chrome
- Soften header, sidebar, dropdown, card, panel, blockquote, and button surfaces to feel more like neutral documentation UI.
- Keep subtle purple interaction feedback for hover, focus, and accent states instead of using purple as the dominant background treatment.
Homepage remains intentionally purple
- Restrict the animated glow treatment to the landing page experience rather than all pages with generic hero content.
- Strengthen the WorkflowHero frame styling so the homepage still reads as branded and visually distinct.
Navigation polish
- Update header-link and tablet-menu hover states to use the new accent tint variables so navigation matches the neutralized theme system.

Example of the new shared theme model:

:root {
  --aw-bg-elevated: rgba(22, 27, 34, 0.88);
  --aw-border: rgba(99, 110, 123, 0.34);
  --aw-text-muted: #9ea7b3;
  --aw-accent-rgb: 168, 139, 250;
}

:root[data-theme='light'] {
  --aw-bg-elevated: rgba(255, 255, 255, 0.88);
  --aw-border: rgba(208, 215, 222, 0.9);
  --aw-text-muted: #57606a;
  --aw-accent-rgb: 130, 80, 223;
}

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot

Pull request overview

This PR retunes the docs site styling toward more neutral GitHub-like surfaces by introducing shared --aw-* theme tokens, shifting most docs chrome away from all-over purple treatments, and keeping the homepage intentionally more branded/purple (including the slide hero framing).

Changes:

Added shared --aw-* theme tokens for backgrounds, borders, muted text, shadows, and accent tinting (light + dark).
Updated global chrome styling (header/sidebar/buttons/cards/blockquotes) to use more neutral surfaces with purple reserved for emphasis/interaction.
Refined landing-page-only glow behavior by keying it to the homepage slide hero ([data-slide-hero]) and strengthened WorkflowHero framing.

Show a summary per file

File	Description
docs/src/styles/custom.css	Introduces `--aw-*` tokens and rebalances light/dark theme surfaces; updates glow gating and various UI surfaces.
docs/src/components/WorkflowHero.astro	Adjusts hero feature/frame styling to keep homepage visually distinct after theme neutralization.
docs/src/components/CustomHeader.astro	Updates hover/accent and dropdown surface styling to use the new shared theme tokens.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 3/3 changed files
Comments generated: 3

pelikhan · 2026-06-20T05:38:27Z

@copilot run to their side and take screenshots.

github-actions · 2026-06-20T05:45:54Z

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #40422 does not have the 'implementation' label (has_implementation_label=false) and has 0 new lines of code in business logic directories (default_business_additions=0, below the 100-line threshold). requires_adr_by_default_volume=false.

github-actions · 2026-06-20T05:46:06Z

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

github-actions · 2026-06-20T05:46:47Z

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. The PR only changes docs/src/components/CustomHeader.astro, docs/src/components/WorkflowHero.astro, and docs/src/styles/custom.css (styling/UI changes). Test Quality Sentinel skipped.

github-actions · 2026-06-20T05:46:55Z

✅ PR Code Quality Reviewer completed the code quality review.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-06-20T05:50:47Z

@copilot run to their side and take screenshots.

Done in ff00ee8. I applied the reviewer-side CSS fixes and captured updated screenshots for the homepage and a non-home docs page from the local docs server.

github-actions

Skills-Based Review 🧠

Applied /zoom-out and /improve-codebase-architecture — requesting changes on three real issues (animation perf, browser compat, body text contrast), with four lower-priority token consistency notes.

📋 Key Themes & Highlights

Issues to address

Animation still runs on all pages — opacity: 0 does not stop the 24 s CSS animation loop on body::before; use display: none instead (or document why animation-in-background is intentional).
Missing -webkit-backdrop-filter on dropdown — the header correctly uses both prefixed and unprefixed variants, but the new dropdown blur only has the unprefixed version and will silently break on Safari.
Body paragraph text demoted to muted colour — --aw-text-muted is reserved for secondary/hint text, but is now applied to .sl-markdown-content p and li, reducing the contrast of primary reading content in light mode.

Token consistency (lower priority)

Light card/panel shadow hardcoded instead of using var(--aw-shadow)
WorkflowHero.astro hero card uses hardcoded rgba values outside the token system (no comment explaining this is intentional)
Light blockquote background hardcoded instead of using an --aw-* surface token
[data-slide-hero] couples global body glow logic to a component-internal attribute — a comment documenting this as a stable contract would help future contributors

Positive Highlights

✅ Clean --aw-* token system is a solid foundation — replacing hundreds of scattered rgba literals with a small set of named variables is the right direction
✅ Scoping the animated glow to the landing page is a clear improvement in both UX and architecture intent
✅ Light theme buttons and card/panel light shadows were genuinely missing before; good catch
✅ Consistent rgba(var(--aw-accent-rgb), ...) pattern for accent tints is elegant

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 87.5 AIC · ⌖ 10.2 AIC · ⊞ 6.9K

github-actions · 2026-06-20T05:54:02Z

+:root[data-theme='light'] .card,
+:root[data-theme='light'] .panel {
+  background-color: rgba(255, 255, 255, 0.88);
+  box-shadow: 0 10px 28px rgba(31, 35, 40, 0.06);


[/improve-codebase-architecture] The dark theme card/panel uses box-shadow: var(--aw-shadow) (line 1071), but the light theme override hardcodes a separate value instead of referencing the same token. This breaks the abstraction: if you later want to tune card shadows, you need to change two places rather than one.

💡 Fix

:root[data-theme='light'] .card, :root[data-theme='light'] .panel { background-color: rgba(255, 255, 255, 0.88); box-shadow: var(--aw-shadow); /* already defined as the lighter value in light :root */ }

--aw-shadow is already set to 0 18px 42px rgba(31, 35, 40, 0.08) in the light theme :root, so this gives the same visual result while keeping the token as the single source of truth.

Addressed in ff00ee8: light .card/.panel now use shared tokens (var(--aw-bg-elevated) and var(--aw-shadow)).

github-actions · 2026-06-20T05:54:02Z

 :root[data-theme='light'] .sl-markdown-content p,
 :root[data-theme='light'] .sl-markdown-content li {
-  color: #424a53;
+  color: var(--aw-text-muted);


[/zoom-out] --aw-text-muted (#57606a in light mode) is defined as the muted/secondary text token — the PR description itself calls it out as for muted text. Applying it to .sl-markdown-content p and li demotes the primary body text of every docs page to secondary contrast. This is the text users come to read; it should use the primary text colour, not the muted one.

💡 Suggestion

Leave body paragraph text at its default (the Starlight --sl-color-text it already inherits), or explicitly set color: var(--sl-color-text). Reserve var(--aw-text-muted) for captions, helper text, and sidebars where reduced contrast is intentional.

Fixed in 6a14821: light-theme .sl-markdown-content p and li now use var(--sl-color-text) instead of the muted token.

github-actions · 2026-06-20T05:54:02Z

-  background: rgba(208, 215, 222, 0.15);
+  border-left-color: rgba(var(--aw-accent-rgb), 0.34);
+  color: var(--aw-text-muted);
+  background: rgba(208, 215, 222, 0.22);


[/improve-codebase-architecture] The dark blockquote background uses the tokenised rgba(110, 118, 129, 0.1) (line 940), but the light override hardcodes rgba(208, 215, 222, 0.22) instead of deriving from an --aw-* token. Minor inconsistency, but it's the kind of stray hardcoded value the token system was introduced to eliminate.

💡 Suggestion

Either define --aw-bg-blockquote in both theme roots, or use the already-defined --aw-bg-subtle as the background base:

background: var(--aw-bg-subtle); /* = #f6f8fa in light, #161b22 in dark */

This keeps blockquote surfaces in sync with the broader neutral surface palette.

Updated in 6a14821: light-theme blockquote now uses var(--aw-bg-subtle) background and var(--sl-color-text) for primary readability.

pelikhan · 2026-06-20T05:56:10Z

@copilot run pr finisher skill

github-actions

REQUEST_CHANGES — 2 new issues + 3 pre-existing issues need fixing before merge

🔍 Summary of all blocking issues

New findings (this review)

Medium — --aw-text-muted on primary body text (light theme) (custom.css:734)
--aw-text-muted: #57606a is GitHub fg.muted — meant for metadata and secondary annotations. Applying it to .sl-markdown-content p and li drops body text contrast from ~7.9:1 to ~5.8:1 on white. Documentation body copy should use the primary text color or a dedicated body token. The same issue applies to light-theme blockquote color at line 948.
Low — Missing -webkit-backdrop-filter on dropdown (CustomHeader.astro:125)
The rest of the codebase pairs backdrop-filter with -webkit-backdrop-filter (e.g. the header). The new dropdown only has the unprefixed form.

Pre-existing open comments (require resolution)

Medium — Animation runs at opacity: 0 on all non-home dark-theme pages (custom.css:433): switching from display: none to opacity: 0 means the compositor still ticks glow-move on every non-homepage, wasting GPU work.
Medium — Same animation waste on light-theme non-home pages (custom.css:131): light-glow-move runs continuously even where the element is invisible.
Medium — .card/.panel light theme reintroduces hardcoded surface values (custom.css:1078): rgba(255,255,255,0.88) and 0 10px 28px ... bypass the --aw-bg-elevated/--aw-shadow tokens introduced by this same PR.

The structural approach (tokenizing via --aw-*, restricting the glow to [data-slide-hero] pages) is the right direction. The issues above are fixable without rearchitecting.

🔎 Code quality review by PR Code Quality Reviewer · 157.2 AIC · ⌖ 7.32 AIC · ⊞ 5.1K

github-actions · 2026-06-20T06:00:10Z

 :root[data-theme='light'] .sl-markdown-content p,
 :root[data-theme='light'] .sl-markdown-content li {
-  color: #424a53;
+  color: var(--aw-text-muted);


Readability regression: --aw-text-muted is applied to primary paragraph and list-item text in the light theme, reducing contrast from ~7.9:1 (#424a53) to ~5.8:1 (#57606a) against a white background.

💡 Details and suggested fix

--aw-text-muted (GitHub fg.muted) is semantically designed for secondary/helper content — timestamps, captions, metadata labels. Applying it to .sl-markdown-content p and li means every paragraph in every light-theme docs page renders at reduced contrast.

GitHub itself uses #1f2328 (fg.default) for body text and reserves #57606a (fg.muted) for secondary annotations. The old #424a53 was closer to the right level for body copy.

Suggested fix:

:root[data-theme='light'] .sl-markdown-content p, :root[data-theme='light'] .sl-markdown-content li { color: var(--sl-color-text); /* use the theme primary text color, not muted */ }

Or introduce a dedicated --aw-text-body token that resolves to a darker value (e.g. #424a53) rather than reusing the muted token.

The same issue applies to blockquote { color: var(--aw-text-muted) } in light mode (line 948) — blockquote content is still primary text, not metadata.

Fixed in 6a14821: reverted light-theme body/list text to var(--sl-color-text) and updated light blockquote text to primary text color.

github-actions · 2026-06-20T06:00:10Z

 		z-index: 1000;
-		box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+		box-shadow: var(--aw-shadow, 0 8px 24px rgba(0, 0, 0, 0.4));
+		backdrop-filter: blur(16px);


Missing -webkit-backdrop-filter: The new dropdown uses backdrop-filter: blur(16px) alone, but the header in custom.css still pairs it with -webkit-backdrop-filter: blur(12px) for consistency across older Safari/WebKit.

💡 Suggested fix

Add the vendor-prefixed form to match the codebase convention:

-webkit-backdrop-filter: blur(16px); backdrop-filter: blur(16px);

While current Safari (18+) supports the unprefixed form, iOS Safari 15/16 which still has noticeable usage, required the prefix. Since the header already uses the paired form, the inconsistency here is the main concern.

Fixed in 6a14821: added -webkit-backdrop-filter: blur(16px) to match the unprefixed backdrop-filter rule.

github-actions · 2026-06-20T06:00:10Z

-  border-left-color: #d0d7de;
-  color: #424a53;
-  background: rgba(208, 215, 222, 0.15);
+  border-left-color: rgba(var(--aw-accent-rgb), 0.34);


Silent border drop on CSS variable failure: rgba(var(--aw-accent-rgb), 0.34) has no fallback for --aw-accent-rgb, so if that variable is unresolved the entire border-left-color declaration is silently discarded by the browser (CSS spec guarantees an invalid computed value when a custom property inside a function has no fallback).

💡 Suggested fix

Add an inline fallback to the var() call:

border-left-color: rgba(var(--aw-accent-rgb, 130, 80, 223), 0.34);

The existing uses of --aw-accent-rgb in CustomHeader.astro and elsewhere already do this correctly (e.g. rgba(var(--aw-accent-rgb, 130, 80, 223), 0.12)). This is the only occurrence that omits the fallback.

Fixed in 6a14821: added fallback in rgba(var(--aw-accent-rgb, 130, 80, 223), 0.34) for the blockquote border color.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2026-06-20T06:09:32Z

@copilot run pr finisher skill

Ran PR finisher pass. Addressed in 6a14821 (text contrast + Safari backdrop filter + accent fallback + contract note), ran local validation (make fmt, make lint, make test-unit, make test, make recompile), and replied to all in-scope review threads. CI on this new agent HEAD is stale and needs a maintainer re-trigger.

github-actions · 2026-06-20T06:40:01Z

@copilot review all comments and address unresolved review feedback.

Generated by 👨‍🍳 PR Sous Chef · 87.7 AIC · ⌖ 1.04 AIC · ⊞ 17.2K · ◷

github-actions · 2026-06-20T06:40:02Z

Refresh CI to clear stale checks and surface the current blocker.

Generated by 👨‍🍳 PR Sous Chef · 87.7 AIC · ⌖ 1.04 AIC · ⊞ 17.2K · ◷

github-actions · 2026-06-20T08:06:06Z

@copilot review all comments and address unresolved review feedback.
Please refresh CI on the current head after the fixes land.

Generated by 👨‍🍳 PR Sous Chef · 51.6 AIC · ⌖ 1.07 AIC · ⊞ 17.2K · ◷

Done

pelikhan · 2026-06-20T13:39:18Z

@copilot render screenshots

Copilot · 2026-06-20T13:45:18Z

@copilot render screenshots

Rendered screenshots from the current branch state:

Homepage: /tmp/gh-aw-screenshots/homepage.png
Non-home docs page (/docs/): /tmp/gh-aw-screenshots/docs-index.png

No repository file changes were needed for this request.

Refresh docs theme styling

03a21f0

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI assigned Copilot and pelikhan Jun 20, 2026

Copilot AI changed the title ~~Refresh docs site theme styling~~ Refresh docs site theme toward neutral GitHub-style surfaces Jun 20, 2026

Copilot created this pull request from a session on behalf of pelikhan June 20, 2026 03:30 View session

Copilot finished work on behalf of pelikhan June 20, 2026 03:30

Copilot AI requested a review from pelikhan June 20, 2026 03:30

pelikhan marked this pull request as ready for review June 20, 2026 05:34

Copilot AI review requested due to automatic review settings June 20, 2026 05:34

Copilot started reviewing on behalf of pelikhan June 20, 2026 05:35 View session

Copilot AI reviewed Jun 20, 2026

View reviewed changes

Comment thread docs/src/styles/custom.css

Comment thread docs/src/styles/custom.css

Comment thread docs/src/styles/custom.css

Copilot started work on behalf of pelikhan June 20, 2026 05:39 View session

github-actions Bot mentioned this pull request Jun 20, 2026

[aw] No-Op Runs #39849

Open

Disable off-home glow animations and align light cards with theme tokens

ff00ee8

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan June 20, 2026 05:51

github-actions Bot requested changes Jun 20, 2026

View reviewed changes

Copilot started work on behalf of pelikhan June 20, 2026 05:56 View session

github-actions Bot previously requested changes Jun 20, 2026

View reviewed changes

Fix docs text contrast and Safari backdrop blur support

6a14821

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot finished work on behalf of pelikhan June 20, 2026 06:10

github-actions Bot mentioned this pull request Jun 20, 2026

[team-status] Team Daily Status — 2026-06-20 #40461

Closed

Copilot started work on behalf of pelikhan June 20, 2026 13:39 View session

Copilot finished work on behalf of pelikhan June 20, 2026 13:45

pelikhan merged commit e11e42a into main Jun 20, 2026
1 check passed

pelikhan deleted the copilot/update-custom-css-themes branch June 20, 2026 14:46

Conversation

Copilot AI commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pelikhan commented Jun 20, 2026

Uh oh!

github-actions Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI commented Jun 20, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Skills-Based Review 🧠

Issues to address

Token consistency (lower priority)

Positive Highlights

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Jun 20, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

REQUEST_CHANGES — 2 new issues + 3 pre-existing issues need fixing before merge

New findings (this review)

Pre-existing open comments (require resolution)

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jun 20, 2026 •

edited

Loading

github-actions Bot commented Jun 20, 2026 •

edited

Loading

github-actions Bot commented Jun 20, 2026 •

edited

Loading

github-actions Bot commented Jun 20, 2026 •

edited

Loading

github-actions Bot commented Jun 20, 2026 •

edited

Loading